home *** CD-ROM | disk | FTP | other *** search
Text File | 1998-11-15 | 53.2 KB | 1,562 lines |
-
-
-
-
- SMTP/POP3 Email Engine
-
- Library for C/C++
-
- (SEE4C)
-
-
-
- USERS MANUAL
-
-
-
- Version 2.1
-
- November 14, 1998
-
-
-
-
- This software is provided as-is.
- There are no warranties, expressed or implied.
-
-
-
-
- Copyright (C) 1998
- All rights reserved
-
-
-
- MarshallSoft Computing, Inc.
- Post Office Box 4543
- Huntsville AL 35815
-
-
- Voice : 256-881-4630
- FAX : 256-880-0925
- email : info@marshallsoft.com
- web : www.marshallsoft.com
-
- _______
- ____|__ | (R)
- --+ | +-------------------
- | ____|__ | Association of
- | | |_| Shareware
- |__| o | Professionals
- --+--+ | +---------------------
- |___|___| MEMBER
-
-
- MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
-
-
-
-
- SEE4C Users Manual Page 1
-
- C O N T E N T S
-
-
-
- Chapter Page
-
-
- 1.0 Introduction................................................3
- 1.1 Email Client Compatibility..............................5
- 1.2 User Support............................................5
- 1.3 ASP Ombudsman...........................................5
- 1.4 Installation............................................6
- 1.5 Consulting Services.....................................6
- 2.0 Library Overview............................................7
- 2.1 Dynamic Link libraries..................................7
- 2.2 Compiler Compatibility..................................7
- 2.3 Compiling Programs......................................7
- 2.4 Using a MAKEFILE........................................7
- 2.5 Using an IDE............................................8
- 2.6 Compiling the Example Programs.........................10
- 3.0 Email Basics...............................................11
- 3.1 Your Email Account.....................................11
- 3.2 Email Address Format...................................11
- 3.3 MIME Extensions........................................11
- 3.4 Your SMTP/POP3 Host Name...............................12
- 3.5 Editing EMAIL.H........................................13
- 3.6 Auto Dial..............................................13
- 4.0 Theory of Operation........................................14
- 5.0 Application Notes..........................................15
- 6.0 Versions of SEE............................................16
- 6.1 Shareware Version......................................16
- 6.2 Student Version........................................16
- 6.3 Professional Version...................................16
- 7.0 Using SEE with Other Languages.............................17
- 8.0 Problems...................................................18
- 9.0 Example Programs...........................................18
- 9.1 SMTP Example Programs..................................18
- 9.2 POP3 Example Programs..................................21
- 10.0 Legal Issues...............................................22
- 10.1 Registration..........................................22
- 10.2 Academic Discount.....................................22
- 10.3 License...............................................23
- 10.4 Warranty..............................................23
- 11.0 Summary................................................... 24
- 11.1 Revision History......................................24
- 11.2 SEE Function Summary..................................25
- 11.3 SEE Error Return Code List............................26
-
-
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 2
-
- 1.0 Introduction
-
- SEE4C is the easiest way to write email applications in C/C++ !
-
- The SMTP/POP3 Email Engine (SEE) is a library of functions providing
- direct and simple control of the SMTP (Simple Mail Transport
- Protocol) and POP3 (Post Office 3) protocols.
-
- A simple interface allows sending and receiving email, including
- multiple MIME BASE64 and quoted-printable encoded attachments.
- Knowledge of Winsock and TCP/IP is not needed. SEE4C includes
- multiple C/C++ example programs.
-
- With SEE4C, you can write GUI or console mode programs that easily:
-
- (1) Send email with optional MIME attachments.
- (2) Get the number of messages on your email server.
- (3) Get the header lines from any email on your server, without
- reading the entire email.
- (4) Delete any email on the server without reading it first.
- (5) Receive any email on your server including MIME attachments.
-
- Fourteen example programs are included, demonstrating the SMTP and
- POP3 functions. Microsoft Foundation Class (MFC) and Borland C++
- Builder (BCB) examples are also included.
-
- SEE4C supports and has been tested with Microsoft Visual C/C++,
- Borland C/C++, and Watcom C/C++ compilers. It can also be used with
- most other Windows compilers.
-
- Both Win16 and Win32 DLLs (Dynamic Link Libraries) are provided.
- SEE4C can be used with Windows 3.X, 95/98, and NT. The SEE4C DLLs
- (SEE16.DLL and SEE32.DLL) can also be used from any language (Visual
- Basic, ACCESS, EXCEL, PowerBASIC Console Compiler, Delphi, Fujitsu
- COBOL, ABSOFT Fortran, etc.) capable of calling the Windows API.
-
- We also have version of the SMTP/POP3 Email Engine for Delphi
- (SEE4D), Visual Basic (SEE4VB) PowerBASIC (SEE4PB), COBOL (SEE4CB),
- and FORTRAN (SEE4F).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 3
-
- 1.0 Introduction (continued)
-
- The following example demonstrates the use of the library:
-
- +-------------------------------------------------------------------+
- | #include <windows.h> |
- | #include <stdio.h> |
- | #include "see.h" |
- | |
- | void main(int argc, char *argv[]) |
- | {int Code; |
- | /* connect to SMTP server */ |
- | seeSmtpConnect( |
- | (LPSTR)"mail.yourserver.net", /* your SMTP server */ |
- | (LPSTR)"user@domain.com", /* your email address */ |
- | (LPSTR)NULL); /* Reply-To header */ |
- | /* send email */ |
- | seeSendEmail( |
- | (LPSTR)"see@marshallsoft.com", /* To list */ |
- | (LPSTR)NULL, /* CC list */ |
- | (LPSTR)NULL, /* BCC list */ |
- | (LPSTR)"SEE Test", /* Subject */ |
- | (LPSTR)"This is a test.", /* Message text */ |
- | (LPSTR)"SEE4C20.ZIP"); /* MIME attachment */ |
- | /* close connection to server */ |
- | seeClose(); |
- | } |
- +-------------------------------------------------------------------+
-
- In the example program above, seeSmtpConnect is called to connect to
- your SMTP mail host. The SMTP server host name and your email address
- are required, while the "Reply-To" entry is optional.
-
- seeSendEmail is then called, passing the addressee lists. The primary
- addressee is provided in the "To List". The CC ("Carbon Copy") lists
- additional recipients, as does the BCC (Blind Carbon Copy) list. The
- subject contains the email subject line. The message text is next. If
- it starts with the '@' symbol, it is considered the name of the file
- containing the email message. Lastly, the filename of any ASCII or
- binary attachment is specified. All fields in seeSendEmail are
- optional except the first.
-
- After returning from seeSendEmail, the seeClose function is called to
- close the connection to the SMTP server.
-
- Refer to the SEE4C Reference Manual for individual function details.
-
-
-
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 4
-
- 1.1 Email Client Compatibility
-
- The SMTP/POP3 Email Engine library has been tested against multiple
- email clients, including Eudora (Lite & Pro), Microsoft Outlook,
- Pegasus, Calypso, PM Mail 98, Actif Mail, Lotus Notes, and Netscape.
-
- 1.2 User Support
-
- We want you to be successful in developing your applications using
- SEE4C! We are committed to providing the best library that we can. If
- you have any suggestions or comments, please let us know.
-
- If you are having a problem using SEE4C, email us at
-
- support@marshallsoft.com
-
- You can also reach us at 256-881-4630 between 8:30 AM and 8:30 PM CST
- Monday through Friday. You can also often contact us on the weekend.
-
- The latest versions of our products are available on our web site at
-
- http://www.marshallsoft.com
-
- and on our anonymous FTP site at
-
- ftp://ftp.marshallsoft.com/marshallsoft
-
- The MarshallSoft Computing newsletter "Comm Talk" is published
- quarterly on our web site. It discusses various communications
- problems and solutions using our products as well as related
- information.
-
- 1.3 ASP Ombudsman
-
- MarshallSoft Computing, Inc. is a member of the Association of
- Shareware Professionals (ASP). ASP wants to make sure that the
- shareware principle works for you. If you are unable to resolve a
- shareware-related problem with an ASP member by contacting the member
- directly, ASP may be able to help. The ASP Ombudsman can help you
- resolve a dispute or problem with an ASP member, but does not provide
- technical support for members' products. Please write to the ASP
- Ombudsman at 157-F Love Ave., Greenwood, IN 26142 USA, FAX
- 317-888-2195, or send email to omb@asp-shareware.org.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 5
-
- 1.4 Installation
-
- (1) Before installation of SEE4C, your Windows C/C++ compiler should
- already be installed on your system and tested. In particular,
- include command line tools when installing your compiler.
-
- (2) Make a backup copy of your distribution disk. Put your original
- distribution disk in a safe place.
-
- (3) Exit Windows into DOS, or start a DOS window:
-
- (4) Create your SEE project directory, copy the SEE archive, then
- unzip the archive. For example:
-
- MKDIR SEE4C
- PKUNZIP SEE4C21.ZIP SEE4C
-
- (5) Run the INSTALL batch file, which will copy the correct DLL and
- LIB files for your compiler. For Win32 compilers, you may choose
- native mode DLLs for your compiler (Microsoft, Borland, or Watcom) or
- "universal" mode, which requires that your compiler support the
- "declspec" keyword. Microsoft VC, Borland 5.0 and Watcom 11.0 all
- support "declspec". The same DLL is used for all Win16 compilers.
-
- INSTALL MS (Microsoft)
- INSTALL BC (Borland)
- INSTALL WC (Watcom)
- INSTALL U (Universal)
-
- (6) Before compiling any example programs, you must edit the file
- EMAIL.H with your email configuration as described in section 3.5.
-
- 1.5 Consulting Services
-
- We offer consulting services at $75 per hour, billed to your credit
- card in 10 minute increments. A work authorization letter must be
- signed and mailed or FAXed to us before we can start.
-
- Questions dealing with the use of our library or our example programs
- are covered as "support", for which there is no charge. Any other
- questions are considered consulting.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 6
-
- 2.0 Library Overview
-
- 2.1 Dynamic Link Libraries
-
- SEE4C includes both Win16 [SEE16] and Win32 [SEE32] dynamic link
- libraries (DLL). A DLL is characterized by the fact that it need not
- be loaded until required by an application program and that only one
- copy of the DLL is necessary regardless of the number of application
- programs that use it. Contrast this to the traditional static library
- which is bound to each and every application that uses it at link
- time.
-
- Since SEE4C is a DLL, only one copy of the SEE4C code is loaded into
- memory regardless of the number of applications programs that use it.
- For example, more than one instance of the test program MAILER can be
- started. All copies of MAILER can run concurrently.
-
- 2.2 Compiler Compatibility
-
- SEE4C has been tested with Microsoft Visual C/C++, Borland C/C++
- (including C++ Builder), Turbo C/C++, and Watcom C/C++. Other Windows
- C/C++ compilers may work as well.
-
- 2.3 Compiling Programs
-
- The example programs can be compiled by using either the provided
- makefiles or creating a project file for the IDE. Separate makefiles
- are provided for Win16 and Win32. 16-bit makefiles end with "16"
- while 32-bit makefiles end with "32".
-
- The various Win32 compiler manufacturers each use different compiler
- settings so that a DLL compiled with one compiler cannot always be
- called by an application compiled with a different compiler.
-
- One solution is the use of the "declspec" keyword provided that your
- compiler supports it. This corresponds to choosing the "universal" set
- of DLLs when installing. See INSTALL.BAT.
-
- 2.4 Using a MAKEFILE
-
- Makefiles originated on UNIX systems. They are the standard way that
- C/C++ programs are constructed in command line environments. Windows
- programs can be constructed with makefiles running DOS using command
- line Windows compilers.
-
- Makefiles are provided for Microsoft, Borland, and WATCOM command line
- compilers. Makefiles have file extensions of "_M_" for Microsoft, "_B_"
- for Borland, and "_W_" for WATCOM. Thus, MAILER16._W_ is the Watcom
- Win16 makefile for MAILER and MAILER32._M_ is the Microsoft Win32
- makefile.
-
- Turbo C/C++ for Windows and Borland C Builder do not support command
- line makefiles. See MAKEFILE.TXT for more information on makefiles.
-
-
-
-
-
- SEE4C Users Manual Page 7
-
- 2.5 Using an IDE
-
- All current windows compilers have an Integrated Development
- Environment (IDE) for building application programs in the Windows
- environment. Since there is no standard format for IDE project files,
- file names must be entered into the IDE from the keyboard. Each
- example program has a project text file (e.g. MAILER.PRJ) which
- contains the list of filenames that must be entered into the IDE.
-
- We do not distribute IDE files in our package because (1) they are
- very large, (2) they are not always upwardly compatible with previous
- versions of a particular IDE, (3) there is no standard project file
- format between compiler manufacturers, and (4) they often must be
- modified to provide the correct path names.
-
- However, creating a project file within the IDE is very easy. Each
- application has a project file . Each project file contains the
- filenames that must be entered into the IDE.
-
- For each IDE, you will have to enter these filenames into the IDE.
- This is usually done with the INS key except for the Microsoft
- Developer, which uses menu commands. Be careful to enter all
- filenames as listed in the ".PRJ" file.
-
- All of the example application programs have been built using IDEs
- from Microsoft, Borland, and Watcom. However, there are differences
- between IDE versions from the same compiler manufacturer.
-
- All of the IDEs use the concept of a file hierarchy. For example, the
- STAT file hierarchy in the IDE (for 32-bit) should look like:
-
- STAT.EXE
- +++ STAT.CPP
- +++ SEE32.LIB
-
- Replace SEE32.LIB above with SEE16.LIB for 16-bit applications. The
- order of the files is not significant.
-
- 2.5.1 Microsoft IDE
-
- Choose "Project", then "New". Select Win16 [Win32] as the target. A
- dialog box will then pop up into which the project file names are
- entered.
-
- 2.5.2 Microsoft Developer
-
- Choose "File", then "New", then "Project Workspace". Select
- "Application" for "Type:" and your project name for "Name:". Choose
- Win16 or Win32 for platform. Then select "Create".
-
- Select "Insert", then "Files into Project". Add all filenames as
- listed in the ".PRJ" file corresponding to the project you are
- building. Lastly, select "Rebuild All".
-
-
-
-
-
- SEE4C Users Manual Page 8
-
- 2.5.3 Borland IDE
-
- Turn off LINKER case sensitivities: Choose "Options", "Projects",
- "Linker", "General". Turn off the "case sensitive link" and "case
- sensitive exports and imports" boxes.
-
- Next, choose "Project", then "New Project". Use the INS (Insert) key
- to pop up a dialog box into which the project file names are entered.
-
- Select "GUI" for the "Target Model:" Only "Runtime" and "Dynamic"
- should be checked for "Standard Libraries:"
-
- NOTE1: If, after linking in the IDE, you get unresolved external
- references to the communications library functions in which each
- function name is all upper case, then you have NOT turned off case
- sensitivity as described above.
-
- NOTE2: If you get errors compiling the windows header file
- "WINDOWS.H", turn on "Borland Extensions" in "Options", "Project",
- "Compiler", "Source".
-
- 2.5.4 Turbo C IDE
-
- Follow the same directions as above, except that the "Target Model:"
- can be any listed.
-
- 2.5.5 Borland C++ Builder
-
- Before compiling using Borland C++ Builder, you must first create
- SEE32_.LIB from SEE32.DLL using the Borland program IMPLIB.EXE
- located in the BIN directory of the Borland C++ Builder installation.
-
- IMPLIB SEE32_.LIB SEE32.DLL
-
- Choose "File" / "Open Project" on the menu bar. Load BCB_PRJ.MAK.
- Then, choose "Build All" from "Project" to create the executable.
-
- 2.5.6 Watcom IDE
-
- Choose "File", then "New Project". Enter the project name and then
- choose Win16 [Win32] as the target. Use the INS (Insert) key to pop
- up a dialog box into which the project file names are entered.
-
- Select "Options" from the main window, then "C Compiler Switches",
- then "10". Memory Models and Processor Switches". Check "80386 Stack
- based calling [-3s]", then check "32-bit Flat model [-mf]".
-
-
-
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 9
-
- 2.6 Compiling Example Programs
-
- There are makefiles provided for each of the example programs.
- For example, to compile QUICK:
-
- For Microsoft C, type:
-
- NMAKE -f QUICK16._M_
- NMAKE -f QUICK32._M_
-
- For Borland C, type:
-
- MAKE -f QUICK16._B_
- MAKE -f QUICK32._B_
-
- For Watcom C, type:
-
- WMAKE -f QUICK32._W_
-
- Several example programs are coded for Win32 Console Mode, and
- therefore can NOT be compiled under Win16.
-
- The QM_PRJ example program requires Borland C++ Builder. The MFC_PGM
- example program requires Microsoft Foundations Classes (MFC).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 10
-
- 3.0 Email Basics
-
- 3.1 Your Email Account
-
- Your email account is hosted on a computer which has a permanent
- connection to the Internet. Email is sent to you over the Internet using
- the SMTP (Simple Mail Transport Protocol) and is stored on disk until
- you retrieve it using the POP3 (Post Office Protocol 3) or IMAP
- (Internet Message Access Protocol) protocol. POP3 is a subset of IMAP,
- so the POP3 protocol can be used to email from a IMAP email server.
-
- The SMTP/POP3 Email Engine (SEE) is used to send and receive email using
- the SMTP and POP3 protocols.
-
- 3.2 Email Address Format
-
- Internet email addresses must all include a domain (the part
- following the @ symbol) and should not include commas, spaces,
- colons, semi-colons, brackets, parentheses, or other such delimiters.
- Generally this would only include alphanumerics, periods, the @
- symbol, the underscore, and the hyphen.
-
- Email addresses are always specified as "xxx<yyy@zzz>" where
-
- (1) xxx is the optional "real name".
-
- (2) yyy@zzz is the official email address,
- where yyy is your account name, and
- zzz is where your email account is hosted.
-
- (3) The brackets are required.
-
- For example, my email address can be specified by any of the
- following:
-
- (1) <mike@marshallsoft.com>
- (2) Mike<mike@marshallsoft.com>
- (3) Mike Marshall <mike@marshallsoft.com>
-
- Multiple email addresses can be stringed together separated by
- commas, as in:
-
- "<mike@myisp.com>,<pam@myisp.com>,<lauren@myisp.com>"
-
- See the sample programs for many examples of use.
-
- 3.3 MIME Extensions
-
- Internet mail can only transport 7-bit ASCII characters. Multipurpose
- Internet Mail Extensions (MIME) are used to allow the attachment of
- binary data to an email message.
-
- The standard MIME attachment types are "quoted-printable" and
- "BASE64". The SMTP/POP3 Email Engine library supports both.
-
-
-
-
- SEE4C Users Manual Page 11
-
- 3.3.1 Quoted-Printable Encoding
-
- Quoted-Printable encoding is primarily used to embed binary values
- into a email message, typically for use with foreign alphabets.
-
- To enable Quoted-Printable encoding, call
-
- seeIntegerParam(SEE_QUOTED_PRINTABLE, 1);
-
- before calling seeSendEmail.
-
- To disable Quoted-Printable encoding, call
-
- seeIntegerParam(SEE_QUOTED_PRINTABLE, 0);
-
- The default is Quoted-Printable encoding off.
-
- 3.3.2 Binary Attachments
-
- Binary attachments are encoded using MIME BASE64. Most all email
- clients (such as made by Eudora, Netscape, and Microsoft) can decode
- MIME BASE64 attachments.
-
- To attach a file to your email, you specify the filename as the last
- argument of the seeSendEmail function. Refer to the reference manual
- (SEE4C_R.TXT) for more details. Multiple attachments are listed with
- commas separating them, such as "file1.zip,file2.zip,file3.zip".
-
- 3.4 Your SMTP/POP3 Host Name
-
- In order to send or receive email, you must know the name (or IP
- address) of your mail server. All email client programs (Eudora,
- etc.) must have this name in order to send email.
-
- Typically, your email server name will be "mail.XXX.YYY" where XXX.YYY
- is the name of the computer which hosts your email account. If you
- aren't sure of your email host name, look in the setup of your email
- client program or ask your system administrator.
-
- Before compiling any example programs, you must edit the file EMAIL.H
- with your email configuration as described in section 3.5.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 12
-
- 3.5 Editing EMAIL.H
-
- The file EMAIL.H contains the following five definitions:
-
- #define SMTP_HOST_NAME "smtp_server_name"
- #define POP3_HOST_NAME "pop3_server_name"
- #define YOUR_EMAIL_ADDR "your_email_address"
- #define POP3_USER_NAME "pop3_account_name"
- #define POP3_PASSWORD "pop3_account_password"
-
- and must be edited with your email configuration before compiling any of
- the example programs. This information is required for all email
- clients. If you are unsure of any of these settings, look in your email
- client program (Eudora, Pegasus, etc.).
-
- SMTP_HOST_NAME is the name (or IP address) of your SMTP email server.
- For example,
-
- #define SMTP_HOST_NAME "mail.hiwaay.net"
- #define SMTP_HOST_NAME "10.240.72.1"
-
- POP3_HOST_NAME is the name of your POP3 server, which is typically the
- same as the SMTP server. For example,
-
- #define POP3_HOST_NAME "mail.hiwaay.net"
- #define POP3_HOST_NAME "10.240.72.1"
-
- Note that your email account is hosted by the POP3 server, although
- you could use another server (SMTP) for sending email.
-
- YOUR_EMAIL_ADDR is your email address. Angle brackets "<>" are
- required. For example,
-
- #define YOUR_EMAIL_ADDR "Mike Marshall<mike@marshallsoft.com>"
-
- POP3_USER_NAME is the account name for your email (POP3) account. For
- example,
-
- #define POP3_USER_NAME "marshallsoft"
-
- POP3_PASSWORD is the password for your email (POP3) account. For
- example,
-
- #define POP3_PASSWORD "qwerty"
-
- 3.6 Auto Dial
-
- To allow Dial-Up Networking (DUN) to dial up your ISP when you access
- the Winsock, use the Windows REGEDIT program to change "00 00 00 00"
- to "00 00 00 01" in the Windows Registry for the entry
- HKEY_CURRENT_USER/Software/Microsoft/Windows/CurrentVersion/Internet
- Settings/EnableAutodial.
-
-
-
-
-
-
- SEE4C Users Manual Page 13
-
- 4.0 Theory Of Operation
-
- The SMTP/POP3 Email Engine is state driven. This means that each call to
- SEE functions (that access the server) is broken down into sequential
- steps, each of which can be performed within a second or two at most.
-
- There are two ways in which SEE is used: (1) indirect use of the
- state engine, and (2) direct use of the state engine.
-
- 4.1 Indirect Method
-
- The first (or "indirect") way to use the SEE library is to allow all SEE
- function calls to automatically call the SEE driver (seeDriver) before
- returning. This is the default way that SEE operates.
-
- The major advantage of this approach is that each SEE function
- returns only after it has completely finished. The disadvantage of
- this approach is that some functions may run for a considerable
- amount of time during which time the calling application must wait.
-
- Refer to the sample programs MAILER and STATUS for an example of this
- approach.
-
- 4.2 Direct Method
-
- The second (or "direct") way that the SEE state driver is used is to
- call it (seeDriver) directly. In order to operate this way, the
- function seeIntegerParam must be called which sets the AUTO_CALL
- flag to off:
-
- seeIntegerParam(SEE_AUTO_CALL_DRIVER, 0);
-
- After the above statement is executed, the state driver (seeDriver)
- must be called after all other SEE functions that access the server.
- For example,
-
- Code = seeSmtpConnect(...);
- if(Code<0) {/* handle error here */}
- while(1)
- {/* call the driver */
- Code = seeDriver();
- if(Code<0) {/* handle error here */}
- if(Code==0) break;
- /* do something here . . . */
- }
-
- The major advantage of the direct approach is that the calling
- application can perform other work such as reporting the progress of
- large downloads. The disadvantage is the extra code that must be
- written to call seeDriver.
-
- Refer to the sample programs FROM and READER for an example of this
- approach.
-
-
-
-
-
- SEE4C Users Manual Page 14
-
- 5.0 Applications Notes
-
- 5.1 Embedded HTML
-
- Some email client programs, such as Microsoft OutLook Express, embed
- HTML (Hyper-Text Markup Language) into the text of their email. This
- is NOT an attachment. You can see what the text should look like by
- viewing it with your web browser.
-
- 5.2 Secure Email
-
- There are two ways to implement secure email using SEE4C. The first
- way is to use a package such as "Pretty Good Privacy" to encrypt your
- message, optionally compress the file using PKZIP or similar product,
- and then send the encrypted message as an attachment.
-
- The second way to implement secure mail is to encrypt your message
- with the encryption software of your choice, then convert the
- (usually binary) encrypted message to ASCII using seeEncodeBuffer. On
- the receive side, you must extract the coded text from the message,
- decode it with seeDecodeBuffer, and then decrypt it with your
- decryption software.
-
- 5.3 Verifying Users
-
- The seeVerifyUser function can be used to verify an email account, as
- demonstrated in the VERUSR example program.
-
- However, some SMTP servers may refuse to connect to non-local
- clients. Those that do may refuse to honor the verify request. This
- means that a negative verify response does NOT mean that the email
- address is necessarily incorrect.
-
- 5.4 Downloading Attachments
-
- Specify a download directory when calling seeGetEmailFile so that you
- don't overwrite any files in the current directory. This is an
- important security precaution.
-
- For example (note the double backslashes):
-
- seeGetEmailFile(1, "email.txt", ".\\download", ".\\download");
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 15
-
- 6.0 Versions of SEE
-
- The SMTP/POP3 Email Engine (SEE) library is available in three versions.
- All three versions have identical functionality.
-
- 6.1 Shareware Version
-
- The shareware version can be differentiated from the other two
- versions by:
-
- (1) The shareware reminder screen is displayed at startup.
-
- (2) The "X-Registered-To: " header in all outgoing email is branded with
- "X-Registered-To: SHAREWARE VERSION [http://www.marshallsoft.com]"
-
- (3) All email is followed by the following two lines:
- "___________________________________________________________________"
- "MarshallSoft SMTP/POP3 Engine. Programmers see www.marshallsoft.com"
-
- The Shareware version may NOT be used for commercial purposes.
-
- 6.2 Student Version
-
- The student version can be differentiated from the other two versions
- by:
-
- (1) There is no shareware reminder screen.
-
- (2) The "X-Registered-To: " header in all outgoing email is branded with
- "X-Registered-To: STUDENT VERSION [http://www.marshallsoft.com]"
-
- (3) There are no lines added to the end of the email as in the
- shareware version.
-
- The Student version may NOT be used for commercial purposes.
-
- 6.3 Professional Version
-
- The professional version can be differentiated from the other two versions
- by:
-
- (1) There is no shareware reminder screen.
-
- (2) The "X-Registered-To: " header in all outgoing email is branded with
- your company name.
-
- (3) There are no lines added to the end of the email as in the
- shareware version.
-
- The professional version may be distributed with your application as
- specified by the software license.
-
-
-
-
-
-
-
- SEE4C Users Manual Page 16
-
- 7.0 Using SEE with Other Languages
-
- The SMTP/POP3 Email Engine DLLs can be used with any application written
- in ANY language capable of calling the Windows (3.1, 95/98, NT) API.
- SEE16.DLL is required for all Win16 (Windows 3.1) applications, and
- SEE32.DLL is required for all Win32 (Windows 95/98/NT) applications.
-
- Declaration files have been defined by the following languages:
-
- C/C++ : SEE.H
- Visual Basic : SEE16.BAS & SEE32.BAS
- EXCEL & ACCESS : SEE16.BAS & SEE32.BAS
- PowerBASIC CC : SEE32.BAS [not the same as above]
- Borland Delphi : SEE16.PAS & SEE32.PAS
- Fujitsu COBOL : SEE32.CBI
- ABSOFT FORTRAN : SEE32.INC
- Visual FoxPro : SEE32.FOX
-
- Additional declaration files will be added. Give us a call if you
- need a declaration not listed above.
-
- If you have interfaced SEE to an unusual language, email us the
- declaration file!
-
- 8.0 Problems
-
- Before attempting to run any of the example programs, you should
- already be able to connect to the Internet and run your email client
- program, such as Eudora or Pegasus Mail.
-
- If you cannot get your application to run properly, first compile and
- run the example programs. If you call us to report a possible bug in
- the library, the first thing we will ask is if the example programs
- run correctly.
-
- Be sure to test the code returned from SEE functions. Then, call
- seeErrorText to get the text associated with the error code.
-
- For example:
-
- Code = seeSmtpConnect("mail.isp.net","<mike@marshallsoft.com>",NULL);
- if(Code<0)
- {static char Buffer[64];
- seeErrorText(Code,Buffer,64);
- printf("Error %d: %s\n", Code, Buffer);
- }
-
- If you encounter a problem that you cannot resolve, give us a call or
- email us at support@marshallsoft.com.
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 17
-
- 9.0 Example Programs
-
- Before compiling any of the example programs, edit the file EMAIL.H
- with your email configuration as explained in section 3.5 "Editing
- EMAIL.H".
-
- Most of the example programs are written in Win32 console mode. This
- was done in order to provide the clearest possible code, without the
- complication and complexity of GUI code. All console mode programs
- can be converted to GUI mode by coding the necessary windows code.
-
- The first example program SEEVER displays the SEE library version
- number and registration string. From the command line, type:
-
- SEEVER
-
- 9.1 SMTP Example Programs
-
- There are 7 SMTP example programs. SMTP programs send email.
-
- 9.1.1 MULTI
-
- MULTI is a Win32 console mode program that connects to a SMTP server
- and sends two email messages. This is the first SMTP example program
- to edit, compile, and run. MULTI takes no arguments.
-
- 9.1.2 MAILER
-
- MAILER is a Win32 console mode program that emails a message, taking
- its input from the command line. For example, to email the file
- TEST.MAI with subject "test" to mike@marshallsoft.com with (optional)
- attachment TEST.ZIP, type
-
- MAILER @test.mai Test "<mike@marshallsoft.com>" test.zip
-
- Note that angle brackets are required around the email address.
-
- 9.1.3 QUICK
-
- QUICK is a Win16/Win32 GUI (Graphical User Interface) application
- that emails a message entered into a dialog box. All necessary
- information is entered at runtime into dialog boxes.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 18
-
- 9.1.4 QM
-
- "Quick Message" (QM_PRJ & QM_PGM) is a Borland C++ Builder (Win32
- GUI) program that emails a message from the GUI. Borland C++ Builder
- is required to compile this program. All necessary information is
- entered at runtime into dialog boxes.
-
- 9.1.5 MFC_PGM
-
- MFC_PGM is a Microsoft Foundation Class (MFC) example program. Win16
- (MFCPGM16.MAK) and Win32 (MFCPGM32.MAK) makefiles are provided. File
- NAFXCW.LIB may have to be copied from MFC\LIB on your Microsoft
- Visual C/C++ CD disk.
-
- 9.1.6 BCAST
-
- BCAST is a Win32 console mode program which emails the same message
- (BCAST.MAI) to a list of addresses taken from the file BCAST.EML
- containing one email address per line. BCAST takes no arguments. To
- start BCAST, type
-
- BCAST
-
- Please DO NOT use this for unsolicited email (SPAM)! Refer to
- BCAST.C for more details of use.
-
- 9.1.7 VERUSR
-
- VERUSR (Verify User) accepts multiple email addresses on the command
- line. It connects to the SMTP server for each email address and
- requests verification of the user. For example, to verify
- msc@traveller.coma and lillian@ro.com, type
-
- VERUSR msc@traveller.com lillian@ro.com
-
- Due to security concerns, some SMTP servers will not honor a "verify
- user" request. A user that does not verify does NOT necessarily mean
- that the email address is not good.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 19
-
- 9.2 POP3 Example Programs
-
- There are 7 POP3 example programs. These examples read email.
-
- 9.2.1 STAT
-
- STAT is a very simple Win32 console modem program that returns the
- number of email messages waiting on the POP3 server. This is the
- first POP3 example to edit, compile, and run. STAT takes no
- arguments. To run STAT, type
-
- STAT
-
- 9.2.2 FROM
-
- FROM is a Win16/Win32 GUI application that reads and displays
- selected header information, without reading the entire email
- message. FROM also makes a very handy utility program.
-
- 9.2.3 STATUS
-
- STATUS is the Win32 console mode equivalent of FROM. STATUS takes no
- arguments. All required information is taken from EMAIL.H. To run
- STATUS, type
-
- STATUS
-
- 9.2.4 DELETE
-
- DELETE is a Win32 console mode program that deletes an email message
- from the server. Be careful! Once deleted, an email message cannot be
- recovered. All required information except the email range to delete
- is taken from EMAIL.H. For example, to delete email messages 2
- through 5, type
-
- DELETE 2 5
-
- Note that email is always deleted in reverse numerical order. Refer
- to seeDeleteEmail in the reference manual (SEE4C_U.TXT) for more
- deatils on deleting.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 20
-
- 9.2.5 READER
-
- READER is a Win32 console mode program that reads an email message,
- including any MIME attachments, saving it to disk. For example, to
- read email message #1 and save it as file MYMAIL.TXT,
-
- READER 1 MYMAIL.TXT
-
- Any attachments are saved to the current directory.
-
- 9.2.6 READS
-
- The READS program is similar to READER except that it reads all email
- from the POP3 server. READS takes no arguments. All required
- information is taken from EMAIL.H. To run, type
-
- READS
-
- Any attachments are saved to the current directory.
-
- 9.2.7 GETDOC
-
- GETDOC is a simple automatic email document retrieval system. It
- looks for commands on the subject line of incoming mail.
-
- If "LIST" is found as the subject of an email (without any email
- body), the GETDOC program emails LIST.TXT to the sender. The LIST.TXT
- file should contain a list of all available documents.
-
- If "GET docname" is found as the subject of an email message (without
- any email body), the GETDOC program emails the requested file
- (docname) to the sender, provided that the requested file is
- available.
-
- GETDOC takes no arguments. All required information is taken from
- EMAIL.H. To run, just type
-
- GETDOC
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 21
-
- 10.0 Legal Issues
-
- 10.1 Registration
-
- The professional version of SEE4C may be registered for $95 plus $7
- S&H ($12 outside of North America) . The professional registered DLLs
- may be distributed (without royalty) in object form only, as part of
- the user's application, provided that the application is NOT a
- compiler, interpreter, or other software development program.
-
- The professional version DLL is also branded with your company name.
-
- To order, contact us as shown on the title page of this manual. All
- prices are guaranteed for one year from the release date.
-
- Multiple copy discounts (3 or more) and site licenses are available.
- Please call for details.
-
- We accept American Express, VISA, MasterCard, Discover, checks in US
- dollars drawn on a US bank, International Postal Money Orders,
- purchase orders (POs) from recognized US schools and companies listed
- in Dun & Bradstreet, and COD (street address and phone number
- required) within the USA (plus a $5 COD charge).
-
- For credit card orders, be sure to include the account number, the
- expiration date, the exact name on the card, and the complete card
- billing address (the address to which the credit card bill is
- mailed), and daytime telephone number.
-
- Print the file INVOICE.TXT if a "Pro Forma" invoice is needed. The
- registered package includes:
-
- o Win16 & Win32 SEE4C Libraries w/o shareware screens.
- o Printed Users Manual & Reference Manual.
- o Telephone and email support for one year.
-
- The registered user will receive the latest version of SEE4C shipped
- by US second day priority mail (packet airmail overseas). A 3.5"
- HD diskette is provided.
-
- 10.2 Academic Discount
-
- We offer an "academic price" of 40% off the normal price for prepaid
- email orders to faculty and full time students currently enrolled in
- any accredited high school, college, or university. To qualify for
- the discount, your school must have a web site and you must have an
- email address at your school.
-
- When ordering, ask for the "academic discount", or enter "student
- at" (or "faculty at") and your schools web site address (URL) in the
- comments field of the order form on our web site order page . Your
- order will be sent to your email address at your school.
-
- This offer is not retroactive and cannot be used with any other
- discount. Products bought with academic pricing can not be used for
- any commercial purpose.
-
-
- SEE4C Users Manual Page 22
-
- 10.3 License
-
- MarshallSoft Computing, Inc. grants the registered user of SEE4C the
- right to use one copy of the SEE4C library (in object form) on a
- single computer in the development of any software product (other
- than libraries such as SEE4C). The user may not use the the library
- on more than one computer at the same time.
-
- The "student" (40% academic discount) registered DLLs may not be
- distributed under any circumstances, nor may they be used for any
- commercial purpose.
-
- The "professional" ($95) registered DLLs may be distributed (without
- royalty) in object form only, as part of the user's application,
- provided that the DLLs are NOT distributed publicly.
-
- 10.4 Warranty
-
- MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO
- THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT
- LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND
- SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC. NOR
- ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR
- DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT,
- CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR
- INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC.
- HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO
- EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH
- DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE
- SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE
- SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE
- SOFTWARE.
-
- Some states do not allow the exclusion of the limit of liability for
- consequential or incidental damages, so the above limitation may not
- apply to you.
-
- This agreement shall be governed by the laws of the State of Alabama
- and shall inure to the benefit of MarshallSoft Computing, Inc. and
- any successors, administrators, heirs and assigns. Any action or
- proceeding brought by either party against the other arising out of
- or related to this agreement shall be brought only in a STATE or
- FEDERAL COURT of competent jurisdiction located in Madison County,
- Alabama. The parties hereby consent to in personam jurisdiction of
- said courts.
-
-
-
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 23
-
- 11.0 Summary
-
-
- 11.1 Revision History
-
-
- Version 1.0 "Beta": May 23, 1998.
-
- o The Beta release.
-
- Version 1.0: June 1, 1998.
-
- o The official release of version 1.0.
-
- Version 2.0: September 14, 1998.
-
- o A major update adding POP3 capability.
- o Another SMTP example program (BCAST).
-
- Version 2.1: November 14, 1998.
-
- o Time zone calculated automatically.
- o Fixed bug in seeClose.
- o Corrected POP3 problem when boundary definition on 2nd line.
- o Added support for alternate MIME boundaries.
- o Added seeVerifyUser function.
- o Added SEE_GET_REGISTRATION, SEE_GET_CONNECT_STATUS,
- SEE_GET_ATTACH_COUNT, and SEE_GET_LAST_RESPONSE.
- o Added GETDOC, SEEVER, and VERUSR example programs.
- o SMTP performance improved.
- o Added seeEncodeBuffer and seeDecodeBuffer functions.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 24
-
- 11.2 SEE4C Function Summary
-
- Refer to the SEE4C Reference Manual (SEE4C_R.TXT) for detailed
- information on the communications and support functions. A one line
- summary of each function follows.
-
- There are 20 functions in the SEE library.
-
- +-------------------+-----------------------------------------------+
- | seeClose | Closes SMTP/POP3 Email Engine. |
- | seeDebug | Returns debug information. |
- | seeDecodeBuffer | Decodes BASE64 buffer. |
- | seeDeleteEmail | Deletes email. |
- | seeDriver | Executes next SEE state. |
- | seeEncodeBuffer | Encodes BASE64 buffer. |
- | seeErrorText | Get text associated with error code. |
- | seeExtractText | Extracts line continuing specified text. |
- | seeGetEmailCount | Get number of emails waiting on server. |
- | seeGetEmailFile | Read email file and save to disk. |
- | seeGetEmailLines | Read email lines into buffer. |
- | seeGetEmailSize | Gets the email size on server. |
- | seeIntegerParam | Sets SEE integer parameter. |
- | seePop3Connect | Connects to POP3 server. |
- | seeSendEmail | Sends email and attachments. |
- | seeSmtpConnect | Connects to SMTP server. |
- | seeStatistics | Returns runtime statistics. |
- | seeStringParam | Sets SEE string parameter. |
- | seeVerifyFormat | Check email address format. |
- | seeVerifyUser | Check email user address with server. |
- +-------------------+-----------------------------------------------+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- SEE4C Users Manual Page 25
-
-
- 11.3 SEE Error Return Code List
-
-
- The complete list of SEE error codes follows.
-
-
- +-----------------------+-----------------------------------------+
- | SEE_NO_ERROR | No error. |
- | SEE_CANNOT_COMPLY | Cannot comply. Not always an error. |
- +-----------------------+-----------------------------------------+
- | SEE_EOF | End of file (socket has been closed). |
- | SEE_IS_BLOCKING | Socket is currently blocking. |
- | SEE_BAD_DOTTED | Bad dotted address. |
- | SEE_TIMED_OUT | Socket timed out awaiting data. |
- | SEE_ABORTED | The DLL has been corrupted. |
- | SEE_ALREADY_CONNECTED | Already connected to server. |
- | SEE_BACK_OVERFLOW | Response buffer has overflowed. |
- | SEE_BAD_ADDRESS_CHAR | Bad character in email address. |
- | SEE_CANNOT_ATTACH | Cannot access WINSOCK |
- | SEE_CANNOT_OPEN | Cannot open file. |
- | SEE_CONNECT_ERROR | Error attempting to connect. |
- | SEE_EMPTY_ADDRESS | EMPTY email address. |
- | SEE_FROM_NULL_ARG | FromPtr is NULL. |
- | SEE_MISSING_AT_CHAR | Missing '@' character in email address. |
- | SEE_MISSING_FROM | Missing FROM email address. |
- | SEE_MISSING_LEFT | Missing '<' delimiter in email address. |
- | SEE_MISSING_RIGHT | Missing '>' terminating email address. |
- | SEE_NOT_CONNECTED | Not connected to server |
- | SEE_NO_RECEIPIENTS | Must have at least one recipient. |
- | SEE_NO_SERVER | Cannot find Smtp server. |
- | SEE_NULL_POINTER | Unexpected NULL pointer. |
- | SEE_RCPT_NULL_ARG | ToPtr is NULL. |
- | SEE_SMTP_ERROR | SMTP returned error. |
- | SEE_SMTP_NULL_ARG | SMTP Server not specified. |
- | SEE_SOCK_READ_ERROR | Socket read error. |
- | SEE_SOCK_WRITE_ERROR | Socket write error. |
- | SEE_TOO_MANY_AT_CHARS | Too many '@' symbols in email address. |
- | SEE_SMTP_ONLY | Must be connected to SMTP server. |
- | SEE_POP3_ONLY | Must be connected to POP3 server. |
- | SEE_USER_NULL_ARG | Required POP3 user argument is missing. |
- | SEE_PASS_NULL_ARG | Required POP3 password argument missing.|
- | SEE_POP3_ERROR | Error returned by POP3 server. |
- | SEE_MSG_NBR_RANGE | Message number out of range. |
- | SEE_FILENAME_NULL_ARG | Required filename is missing. |
- | SEE_EMAIL_PATH_NULL | Required file path is missing. |
- | SEE_CANNOT_CREATE | Cannot create file. |
- | SEE_BUFFER_NULL_ARG | Required buffer is missing. |
- +-----------------------+-----------------------------------------+
-
- NOTES:
- (1) All error codes are negative.
- (2) Numerical error codes are defined in DEFINES.H.
- (3) SEE_ABORTED will be returned if the DLL has been modified. You
- should never get this message!
-
-
-
- SEE4C Users Manual Page 26
-
-